// 用 cargo doc 构建文档到 target/doc。
// 用 cargo test 运行所有测试（包括文档测试），用 cargo test --doc 仅运行文档测试。
// 这些命令会恰当地按需调用 rustdoc（以及 rustc）。

// #![crate_name = "doc"]

/// 这里给出一个“人”的表示
pub struct Person {
    /// 一个人必须有名字（不管 Juliet 多讨厌她自己的名字）。
    name: String,
}

// inline属性用于内联文档，而不是链接到单独的页面。
#[doc(inline)]
pub use bar::Bar;

/// bar 的文档
mod bar {
    /// Bar 的文档
    pub struct Bar;
}

// no_inline属性用于防止链接到单独的页面或其他位置。
// 来自 libcore/prelude 的例子
// #[doc(no_inline)]
// pub use crate::mem::drop;

// hidden属性告诉 rustdoc 不要包含此项到文档中
// 来自 futures-rs 库的例子
// #[doc(hidden)]
// pub use self::async_await::*;

impl Person {
    /// 返回具有指定名字的一个人
    ///
    /// # 参数
    ///
    /// * `name` - 字符串切片，代表人的名字
    ///
    /// # 示例
    ///
    /// ```
    /// // 在文档注释中，你可以书写代码块
    /// // 如果向 `rustdoc` 传递 --test 参数，它还会帮你测试注释文档中的代码！
    /// use doc::Person;
    /// let person = Person::new("name");
    /// ```
    pub fn new(name: &str) -> Person {
        Person {
            name: name.to_string(),
        }
    }

    /// 给一个友好的问候！
    /// 对被叫到的 `Person` 说 "Hello, [name]" 。
    pub fn hello(&self) {
        println!("Hello, {}!", self.name);
    }
}

fn main() {
    let john = Person::new("John");

    john.hello();
}
